Docs: Add CONTRIBUTING.md#1139
Conversation
nbriannl
changed the title
nbriannl
changed the title
|
Questions:
Observations:
|
|
We have a forum? |
nbriannl
changed the title
Sorry, should be issue tracker. |
nbriannl
force-pushed
the
816-contributing
branch
from
7c87059 to
234cac0
Compare
openorclose
left a comment
openorclose
left a comment
There was a problem hiding this comment.
Where should we put contributing.md?
Otherwise LGTM
|
Could possibly put a link to the contributing page in readme.md like in https://github.com/gatsbyjs/gatsby |
nbriannl
force-pushed
the
816-contributing
branch
from
234cac0 to
f0341b6
Compare
|
@Tejas2805 as someone from a another project, how is contributing.md from the perspective of a new contributor? |
Tejas2805
left a comment
Tejas2805
left a comment
There was a problem hiding this comment.
Took a look at it. Looks promising! Few comments:
- Few typos here and there and grammatical errors.
- I still don't know what to do after my PR is open and all checks pass - Should I wait? Or should I request for a review? If so, how to request for one. (Can add something related to this)
- You can maybe also add a bit about how much time a PR's review will take? So that the contributor can accordingly set his expectations.
| The Developer Guide can be found at https://markbind.org/devdocs/devGuide/index.html No newline at end of file | ||
| The Developer Guide can be found at https://markbind.org/devdocs/devGuide/index.html | ||
|
|
||
| If you're interested in contributing to MarkBind, we'd love to have you onboard. Check out our [Contributing Guide](https://markbind.org/devdocs/devGuide/contributing) for ideas on contributing and setup steps for getting our repositories up and running on your local machine. No newline at end of file |
There was a problem hiding this comment.
Contribution Guide (might sound better)
|
@Tejas2805 thanks for you feedback,
As far as I know, if I think I'm ready, I usually request for a review from the current Markbind team members this semester, and then ask for a review from one of the maintainers. How to ask for a review is https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/requesting-a-pull-request-review over here. In terms of who is actively contributing and maintaining at any time, the people will definitely change as time goes by. I don't have a fixed answer for that. A good rule of thumb to determine who are the active contributors, is just by seeing who's actively PRing and posting issues. And to determine who's actively maintaining, usually it's whoever is merging the PRs (in case case would be @marvinchin)
I don't have an solid answer for this. Depends on how active the team is. In any case, I'll update the docs with the corresponding info. 😄 |
|
Maybe then you just guide them to the link or something. Will be better that way I feel. |
|
|
||
| ### How to report a bug | ||
|
|
||
| Report bugs in our [issue tracker](https://github.com/MarkBind/markbind/issues), following the guideslines below. Following the guidelines helps us in undestanding your report better and reproduce the behavior more easily. |
There was a problem hiding this comment.
understanding
and reproduce the behavior more easily
|
|
||
| Report bugs in our [issue tracker](https://github.com/MarkBind/markbind/issues), following the guideslines below. Following the guidelines helps us in undestanding your report better and reproduce the behavior more easily. | ||
|
|
||
| - Has your bug been raised up before? Before reporting a bug, please search if it has been already reported in the existing issues. |
There was a problem hiding this comment.
Has your bug been raised up before?
linking issues to our issues page would be nice
| - Is your bug from the current version or an older version of MarkBind? What OS are you on? Tell us about your environment, for example, the MarkBind version you are on. | ||
| - What did you do? What did you expect to happen? What actually happened? | ||
| - Include the actual MarkBind code causing the issue, the steps for reproduction, the actual, raw output, and what you expect instead. This helps us to reproduce the bug to understand it better. | ||
| - You are also encouraged to submit a PR that reproduces this in `test\functional\test_site\bugs\`. |
There was a problem hiding this comment.
should we use unix style slashes here instead?
| - Has your bug been raised up before? Before reporting a bug, please search if it has been already reported in the existing issues. | ||
| - Is your bug from the current version or an older version of MarkBind? What OS are you on? Tell us about your environment, for example, the MarkBind version you are on. | ||
| - What did you do? What did you expect to happen? What actually happened? | ||
| - Include the actual MarkBind code causing the issue, the steps for reproduction, the actual, raw output, and what you expect instead. This helps us to reproduce the bug to understand it better. |
There was a problem hiding this comment.
Including things such as the actual MarkBind code .... actual raw output ... instead can help us in diagnosing the issue quicker
| - Include the actual MarkBind code causing the issue, the steps for reproduction, the actual, raw output, and what you expect instead. This helps us to reproduce the bug to understand it better. | ||
| - You are also encouraged to submit a PR that reproduces this in `test\functional\test_site\bugs\`. | ||
|
|
||
| Please do not submit personal support requests as bugs, [submit a blank issue](https://github.com/MarkBind/markbind/issues/new) to our issue tracker and label it with <a href="https://github.com/MarkBind/markbind/issues?q=is%3Aopen+is%3Aissue+label%3Aquestion" class="badge" style="color:white; background-color: #A41BD6;">question</a>. |
There was a problem hiding this comment.
If you need help, feel free to submit a.... with a label of ...
There was a problem hiding this comment.
Help has two meanings
- 'I'm a contributor that there's some aspect of markbind (or its workflow) I don't understand'
- 'I'm a user trying to make a markbind site, and I don't understand X'
I'm trying to mean the former with 'personal support requests'
Are you referring to that definition as well?
There was a problem hiding this comment.
Ahh good point, I think its naturally clear to someone reading the contributing guide that its the former though. You could add on if not.
There was a problem hiding this comment.
Oh. I mean the latter 😆
There was a problem hiding this comment.
Could be both as well, I would just leave it as it is :)
|
|
||
| ### How to request a feature | ||
|
|
||
| Request for new features or enhancements to existing features in our [issue tracker](https://github.com/MarkBind/markbind/issues), following the guideslines below. Following the guidelines helps us in undestanding what your problem or use case is, so that contributors may know exactly what feature to implement. |
There was a problem hiding this comment.
Could add a introductory sentence: We welcome suggestions to improve markbind as well. To do so, ....
There was a problem hiding this comment.
understanding your request better so that contributors may know exactly what feature to implement
|
|
||
| Request for new features or enhancements to existing features in our [issue tracker](https://github.com/MarkBind/markbind/issues), following the guideslines below. Following the guidelines helps us in undestanding what your problem or use case is, so that contributors may know exactly what feature to implement. | ||
|
|
||
| - Has someone already requested your feature before? Before requesting a new feature, please search if it has been already requested in the existing issues. |
There was a problem hiding this comment.
Similar to a bug report, please search if ...
There was a problem hiding this comment.
wrap with I have an issue when [...]
| - Is your request related to a problem? Provide a clear and concise description of what the problem is. Eg: I have an issue when [...] | ||
| - Describe the solution you'd like. Provide a clear and concise description of what you want to happen. | ||
| - Describe alternatives you've considered. Let us know about other solutions you've tried or researched. | ||
| - If any, share some additional context. Is there anything else you can add about the proposal? You might want to link to related issues here if you haven't already. |
There was a problem hiding this comment.
You can also share some additional context ... e.g. ...
You might want to link to related issues here if you haven't already. is for when you're writing the request template, so let's remove it here
|
|
||
| Unsure where to begin contributing to MarkBind? You can start by looking through these issues marked <a href="https://github.com/MarkBind/markbind/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+sort%3Acomments-desc" class="badge" style="color:white; background-color: #7057FF;">good first issue</a>. | ||
|
|
||
| It is recommended you go through the [Getting Started](https://markbind.org/userGuide/gettingStarted.html) section in the User Guide, and play around with Markbind with your own basic site in order to explore and understand the various features it provides. |
There was a problem hiding this comment.
We recommend ... to play around with Markbind first. Explore and understand ...
There was a problem hiding this comment.
Could also recommend visiting devGuide.md first to learn how to setup the dev environment, run tests, etc
|
|
||
| Reviewer(s) may request additional changes from you in terms of implementation, design, tests, style, or other changes before your pull request is finally approved. | ||
|
|
||
| ## How to Test |
There was a problem hiding this comment.
Could leave this to the above recommendation
|
|
||
| ### How to report a bug | ||
|
|
||
| Report bugs in our [issue tracker](https://github.com/MarkBind/markbind/issues), following the guideslines below. Following the guidelines helps us in undestanding. |
There was a problem hiding this comment.
repitition of Following the guidelines, could change the second one to This
undestanding -> understanding
ang-zeyu
left a comment
ang-zeyu
left a comment
There was a problem hiding this comment.
Just 2 more nits, LGTM otherwise 👍
| - You are also encouraged to submit a PR that reproduces this in `test/functional/test_site/bugs/`. | ||
|
|
||
| If you need help, feel free to [submit a blank issue](https://github.com/MarkBind/markbind/issues/new) to our issue tracker and with a label of question <a href="https://github.com/MarkBind/markbind/issues?q=is%3Aopen+is%3Aissue+label%3Aquestion" class="badge" style="color:white; background-color: #A41BD6;">question</a>. | ||
| Please do not submit personal support request (eg: "How do I use X?") as bugs. Instead, feel free to [submit a blank issue](https://github.com/MarkBind/markbind/issues/new) to our issue tracker and with a label of <a href="https://github.com/MarkBind/markbind/issues?q=is%3Aopen+is%3Aissue+label%3Aquestion" class="badge" style="color:white; background-color: #A41BD6;">question</a>. |
|
|
||
| When you're ready, you can start by looking through these issues marked <a href="https://github.com/MarkBind/markbind/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+sort%3Acomments-desc" class="badge" style="color:white; background-color: #7057FF;">good first issue</a>. | ||
|
|
||
| If you need help, be it regarding MarkBind or our workflow, feel free to [submit a blank issue](https://github.com/MarkBind/markbind/issues/new) to our issue tracker and with a label of <a href="https://github.com/MarkBind/markbind/issues?q=is%3Aopen+is%3Aissue+label%3Aquestion" class="badge" style="color:white; background-color: #A41BD6;">question</a>. |
nbriannl
force-pushed
the
816-contributing
branch
from
407d912 to
d2ac641
Compare
marvinchin
left a comment
marvinchin
left a comment
There was a problem hiding this comment.
Looks like a good addition to help new contributors find their way around. Just some nits from me ⭐️
|
|
||
| Unsure where to begin contributing to MarkBind? | ||
|
|
||
| We recommend to visit the [Getting Started](https://markbind.org/userGuide/gettingStarted.html) section in the User Guide and play around with Markbind first. Explore and understand the various features it provides. |
There was a problem hiding this comment.
Suggestion:
We recommend to visit that you start off by visiting the Getting Started section in the User Guide and play around with Markbind first trying out MarkBind as a user.
|
|
||
| We recommend to visit the [Getting Started](https://markbind.org/userGuide/gettingStarted.html) section in the User Guide and play around with Markbind first. Explore and understand the various features it provides. | ||
|
|
||
| If you have not done so yet, we also recommend to visit the [Developer Guide]({{baseurl}}/devGuide/index.html) to learn about the [structure of the project]({{baseurl}}/devGuide/index.html#project-structure), how to set up the [developer environment]({{baseurl}}/devGuide/index.html#development-process), and how to run [tests]({{baseurl}}/devGuide/devGuide.html#testing). |
There was a problem hiding this comment.
recommend to visit -> recommend visiting?
|
|
||
| If you have any questions, be it regarding MarkBind or our workflow, feel free to [submit a blank issue](https://github.com/MarkBind/markbind/issues/new) to our issue tracker with a label of <a href="https://github.com/MarkBind/markbind/issues?q=is%3Aopen+is%3Aissue+label%3Aquestion" class="badge" style="color:white; background-color: #A41BD6;">question</a>. | ||
|
|
||
| ### How to make Pull Requests to Submit changes? |
There was a problem hiding this comment.
How to make Pull Requests to submit changes?
|
|
||
| ### How to request a feature | ||
|
|
||
| We welcome suggestions to improve markbind as well. To do so, you can request for new features or enhancements to existing features in our [issue tracker](https://github.com/MarkBind/markbind/issues), following the guidelines below. This helps us in undestanding your request. |
nbriannl
force-pushed
the
816-contributing
branch
from
d2ac641 to
99b08de
Compare
nbriannl
force-pushed
the
816-contributing
branch
from
99b08de to
390ae8a
Compare
nbriannl
force-pushed
the
816-contributing
branch
from
390ae8a to
49dbd08
Compare
Update docs and readme
nbriannl
force-pushed
the
816-contributing
branch
from
49dbd08 to
49423b4
Compare
…bind into remove-fixed-bugs * 'remove-fixed-bugs' of https://github.com/Tejas2805/markbind: Docs: Add contributing.md (MarkBind#1139) Show pointer and use underline dashed for click trigger (MarkBind#1111) Support variables to be defined as by JSON (MarkBind#1117) Allow an array for specifying page src or glob (MarkBind#1118) Code blocks: Implement inline markdown support for heading (MarkBind#1137) Fix lazy reload for urls without index (MarkBind#1110) Changes remaining references from filterTags to tags (MarkBind#1149)
6 participants
What is the purpose of this pull request? (put "X" next to an item, remove the rest)
• [X] Documentation update
• [ ] Bug fix
• [ ] New feature
• [ ] Enhancement to an existing feature
• [ ] Other, please explain:
Fixes #816
What is the rationale for this request?
A CONTRIBUTING.md provides a beginner's guide for contributors. We shouldn't rebuild the wheel regarding some topics such as setting up the environment, which is covered under 'Development Process' as well as Testing. The main objective of CONTRIBUTING.md should instead be to introduce to the open source nature of the repo.
Reference has been taking from the following documentation and guides:
https://www.gatsbyjs.org/contributing/
https://mozillascience.github.io/working-open-workshop/contributing/
https://github.com/atom/atom/blob/master/CONTRIBUTING.md
What changes did you make? (Give an overview)
Added documentation
Is there anything you'd like reviewers to focus on?
Are there other information to include in contributing.md?
I don't expect this to be quickly merged. Let's work together to make first time contributing an easy experience with a low barrier to entry.
Testing instructions:
View the page at https://deploy-preview-1139--markbind-master.netlify.com/devguide/contributing
Proposed commit message: (wrap lines at 72 characters)
Docs: Add CONTRIBUTING.md